/**
 * Hackystat Version 8 Framework
 * Twitter Widget RPC Interface
 */
package org.hackystat.ui.hackerrific.client.common;

import java.util.ArrayList;

import com.google.gwt.user.client.rpc.RemoteService;

/**
 * Remote procedure call interface for communicating with the Twitter server. 
 * 
 * @author David J. Nickles
 */
public interface RPCRemoteService extends RemoteService {
  
  /**
   * Returns an HTTP 200 OK response code and a format-specific response if authentication
   * was successful.  Use this method to test if supplied user credentials are valid with 
   * minimal overhead.
   * @param user user to authentication
   * @param password user password for authentication
   * @return true if the credentials are valid with the twitter server.
   */
  public Boolean authenticate(String user, String password);
  
  /**
   * Favorites the status specified in the ID parameter as the authenticating user.
   * Returns the favorite status when successful.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @param id Required.  The ID of the status to favorite.
   * @return true if successful, false if not failed.
   */
  public Boolean createFavorite(String user, String password, String id);
  
  /**
   * Unfavorites the status specified in the ID parameter as the authenticating user.
   * Returns the favorite status when successful.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @param id Required.  The ID of the status to favorite.
   * @return true if successful, false if not failed.
   */
  public Boolean destroyFavorite(String user, String password, String id);
  
  /**
   * Ends the session of the authenticating user, returning a null cookie.
   * 
   * @param user the authenticating twitter user.
   * @param password the authenticating twitter password.
   * @return true if successful, false if not failed.
   */
  public Boolean endSession(String user, String password);

  /**
   * Returns the 20 most recent statuses from the Twitter server for the specified feed type.
   * @param user user to authentication
   * @param password user password for authentication
   * @param type the timeline type: public, friends, user
   * @param lastId get entries since the last entry id
   * @throws RPCException if problems occur during the Twitter Restlet call.
   * @return formatted array of the Twitter feed.
   * 
   * @gwt.typeArgs <java.util.ArrayList<java.lang.String>>
   */
  public ArrayList timeline(String user, String password, String type, String lastId) 
    throws RPCException;
  
  /**
   * Send a tweet to the Twitter server.
   * @param user user to authentication
   * @param password user password for authentication
   * @param message the tweet text
   * @throws RPCException if problems occur during the SensorBase procedure call
   * @return if the update was successful or not
   */
  public Boolean update(String user, String password, String message) throws RPCException;
  
  /**
   * Returns the version number from the Manifest file.
   * 
   * @return String the version number from the Manifest file.
   */
  public String version(); 
}
